package com.thitech.sif.socket;

import java.io.InputStream;

import com.thitech.sif.Executor;
import com.thitech.sif.Helper;
import com.thitech.sif.exception.InputException;
import com.thitech.sif.exception.OutputException;

/**
 * <pre>
 * Socket服务封装方法回调街口，本接口专供没有提供Jar包的Socket系统使用
 * 
 * 1、doInput方法功能：组织服务调用时的Socket报文，并把组织好的报文以字符串格式返回。如果在
 * 组织请求报文时出现异常，则把异常转换成InputException，并抛出。
 * 
 * 2、getResult方法功能：通过方法中的InputStream参数取Socket服务的返回值，并把返回值组织成
 * SocketBaseOutput对象返回。在处理返回数据时，如果出现异常，则把异常转换成OutputException。
 * SocketBaseOutput对象中的SIFReturn对象也在该方法中赋值，注意：一定要把Socket
 * 中返回的值放在该对象中。且要调用SocketBaseOutput对象的setResponseString方法，把从InputStream
 * 中获取到的字符串报文也存入SocketBaseOutput对象的responseString属性中。
 * </pre>
 * 
 * @author shisheng.lian
 * @date 2014-04-10
 */

public interface SocketHelper extends Helper {
	
	/**
	 * 组织服务调用时的Socket报文，并把组织好的报文以字符串格式返回。如果在
	 * 组织请求报文时出现异常，则把异常装换成InputException，并抛出。
	 * 
	 * @param executor  Socket服务执行对象，包含所有服务调用所需要的上下文数据对象
	 * @return 返回组织好的请求报文
	 * @throws InputException
	 *           组织报文时如果出现异常，则全部转换成该异常并抛出。
	 */
	public String doInput(Executor executor) throws InputException;
	
	/**
	 * 通过方法中的InputStream参数取Socket服务的返回值，并把返回值组织成
	 * SocketBaseOutput对象返回。在处理返回数据时，如果出现异常，则把异常转换成OutputException。
	 * SocketBaseOutput对象中的CPSServiceReturnCode对象也在该方法中赋值，注意：一定要把Socket
	 * 中返回的值放在该对象中。并把返回回来的报文转换成字符串，存储在SocketBaseOutPut对象的responseString
	 * 字段中，该字段为必输字段，如果为空则框架会抛出异常。
	 * 
	 * @param in
	 *            Socket输入流对象。该对象由框架自动获取，封装时只要使用，其它的例如关闭该对象的操作都由框架自动完成
	 * @param executor
	 *            Socket服务执行对象，包含所有服务调用所需要的上下文数据对象
	 * @return 返回处理好的结果给流程使用
	 * @throws OutputException
	 *             如果处理返回结果时出现异常，则转换成该异常抛出。
	 */
	public SocketBaseOutput getResult(InputStream in, Executor executor) throws OutputException;
}
